feat: detect platform deployment env declarations and code references - #22

Stacked on #21 (feat/detect-env). Everything is opt-in: --with-env reads manifest/config/deployment files only; the source-file search needs --with-source as well (--with-source without --with-env is a clap error).

Summary

brainpod detect --with-env now also reports:

• Platform deployment manifests: Heroku/Dokku app.json, Scalingo scalingo.json, heroku.yml, Render render.yaml, Fly.io fly.toml, DigitalOcean .do/app.yaml/.do/deploy.template.yaml, Vercel vercel.json/vercel.toml (legacy env/build.env), Netlify netlify.toml (build, context and template environments), Google App Engine app.yaml (only when runtime is present), and AWS Copilot copilot/*/manifest.yml. Railway and Koyeb are excluded: Railway's config files hold no variables and its replacement is executable code, and Koyeb has no repository file.
• New optional record fields: required, secret, generated, hasDefault and scope. Each is set only where the manifest states it. Database, service and secret wiring uses feat: detect environment declarations with --with-env #21's reference shape: Render fromDatabase/fromService/fromGroup, DigitalOcean ${db.VAR}/${APP_URL} bindings, Vercel @secret, and Copilot SSM, Secrets Manager and CloudFormation references.
• Dockerfile ARG: reported like ENV, with scope: "build" and a hasDefault boolean. This updates feat: detect environment declarations with --with-env #21's statement that ARG is not inferred.
• Code references (--with-env --with-source only): a literal, catalog-driven search of source files for platform-injected names and framework env prefixes:
  • Platforms: Vercel, Netlify, Render, Railway, Heroku, Fly.io, Cloudflare Pages, App Engine, Cloud Run and Koyeb.
  • Frameworks: NEXT_PUBLIC_, VITE_, REACT_APP_, NUXT_PUBLIC_/NUXT_, PUBLIC_ (only in projects detected as SvelteKit or Astro), EXPO_PUBLIC_, GATSBY_, VUE_APP_ and others.
  • Patterns live as data in rules.toml catalog.code_references, each with its primary documentation link.
  • Each (project, name) becomes one format: "code-reference" record with origin, provider, scope, up to 20 file/line occurrences and occurrenceCount.
  • Generic names (URL, CONTEXT, PORT, …) are never cataloged. Moderately generic documented names are reported only when the platform's manifest exists in the repository.

Platform adapters live in src/detect/environment/platforms.rs and the code-reference matcher in src/detect/environment/references.rs. There are no new dependencies: TOML uses the existing toml crate, and platform JSON uses serde_json. JSON keeps the last value of a duplicate key, as these platforms do; Chatwoot's app.json has one.

Read impact

Measured on the 56 pinned repositories. Times are the median of per-repository five-run warm medians on a loaded host, including CLI startup and serialization.

--with-env reads no application source; the 66 extra files compared with #21 are the platform manifests. Only --with-source reads source files. Without flags, reads and output are unchanged.

Privacy

Names and provenance only. No values are returned in JSON, text, diagnostics or retained facts, including defaults, generated values, secret values, DigitalOcean EV[...] values and Netlify template labels. Nothing is evaluated, expanded, fetched or executed. Source files are only split into identifier tokens; no code text is kept. SSM paths, ARNs and other non-simple targets are dropped. Malformed input produces fixed, redacted diagnostics. Synthetic tests assert that DO_NOT_DISCLOSE markers never appear in output.

Validation

• cargo test --locked: 231 passed, 3 ignored benchmarks not run. The offline cache lacks serde-saphyr, so this ran online. New tests check that --with-env alone reads no source files and emits no code-reference records, and that clap rejects --with-source without --with-env.
• cargo fmt --all -- --check: passed.
• cargo clippy --all-targets -- -D warnings: with clippy 0.1.98 there are 4 errors in unchanged code (deno.rs question_mark, generated tunnel protobuf result_large_err); the base branch reports the same 4. With only those two lints allowed, clippy is clean.
• Python audit-runner tests: 13/13. The runner gains --with-source. Code-reference corpus checks are stored as sourceChecks and run only in that mode; declaration checks run in both opt-in modes.
• Corpus audit, 56/56 repositories with 5 deterministic runs (51 existing plus 5 pinned supplements for Render, DigitalOcean, Copilot, App Engine and app.json):
  • No flags: 300/300.
  • --with-env: 348/348, including 48/48 declaration checks (22 new).
  • --with-env --with-source: 353/353, adding 5/5 sourceChecks.
  • All 56 no-flag JSON reports are byte-identical to the feat: detect environment declarations with --with-env #21 base binary, and the projects arrays in both opt-in modes equal the no-flag ones.
• One existing feat: detect environment declarations with --with-env #21 assertion, hyperswitch EXTRA_FEATURES absent, encoded "ARG is not inferred". It now asserts that no non-build record exists, plus a positive build-scoped ARG check.
• Not run: native OS CI and the Brainpod starter branches.

See tests/detect-env.md for the platform research (included and excluded, with doc links), the field mapping per format, the code-reference rules and pattern table with sources, and full results.